Dialog: Input Configuration

Symbol:

Function: The dialog allows you to assign an input action to an input event and to configure the input action.

Call: Configure button in the Input configuration property

Requirement: An element is selected in the editor.

Are all element properties available?

All properties are available only after you select the Advanced option or the All categories filter in Properties.

Input action: User Management

Dialogs and actions	Configures which one of the possible user management dialogs or which action follows the input event Note The dialog used at runtime is configured in the Dialog Settings tab of the Visualization Manager. . See also Login dialog Change password dialog Change configuration dialog Default: Dialogs from the `VisuUserManagement` library
Login	The login prompt opens. Default: `VisuUserManagement.VUM_Login` in Login dialog
Logout	The current user is logged out.
Change User Password	The dialog for changing the password opens. Default: `VisuUserManagement.VUM_ChangePassword` in Change password dialog
Open User Configuration	The dialog opens for changing the configuration. Default: `VisuUserManagement.VUM_UserManagement` in Change configuration dialog

Input action: Close Dialog

Dialog

The visualization of type Dialog which will be closed

: List box with all Dialog type visualizations available in the project

Example:

. Default dialogs of the VisuDialogs library, which is usually integrated in the project.

FileOpenSave
Keypad
Login
Numpad
NumpadExtended
TextinputWithLimits

Note

The setting in the object property (Visualization tab) of a visualization determines whether or not a visualization can be used as a dialog.

Result	Return value for closing the dialog Note If there are more input actions after closing, then they configured in the Input configuration → OnDialogClosed property of the element.
None	: No return value
OK	: The set return value is returned. The return value refers to the button in the dialog. The value `OK` is returned for the OK button. The value `Cancel` is returned for the cancel button.
Cancel
Abort
Retry
Ignore
Yes
No

Input Action: Open Dialog

Dialog

Name of the visualization (type: Dialog) which will open as a dialog at runtime after the input action has been triggered by the visualization user

: List box with all dialogs available in the project.

Note

The VisuDialogs library provides standard dialogs.

VisuDialogs.FileOpenSave
VisuDialogs.Login

Transfer parameters of the dialog
Parameters	Interface parameter as declared in the interface editor of the visualization Example: `filelistProvider`
Type	Data type of the parameter as declared in the interface editor of the visualization Example: `VISU_FBFILELISTPROVIDER`
Value	Variable (data type corresponds to the data type of the parameter) The value of the variable is passed to the parameter when the dialog opens. Example: `PLC_PRG.fileListProvider // Instance of function block VisuDialogs.Visu_FbFileListProvider` : The Input Assistant offers all variables available in the entire project.

Here the return value of the dialog is activated for which the `Var_OUTPUT` variable and `VAR_IN_OUT` variable are written. The dialog closes afterwards.
Updateandin case of result	Note The parameters are updated before the dialog is closed. Until then, the values are stored temporarily. They are stored as a copy, not as a reference.
None	: No return value
OK	: Defines the return value for which the transfer parameter is written
Cancel
Exit
Retry
Ignore
Yes
No

Open dialog modal

standard icon : At runtime, only the dialog processes user input. User input which occurs outside of the dialog is ignored. The user interface there is blocked.

Position to Open	Initial position of the opening dialog relative to the calling visualization
Centered	: The dialog is displayed in the center.
Position	: The dialog is displayed at the position set below. Note: Use the corresponding input options for specifying the position in the X-direction and the Y-direction.
X	Horizontal X-position for the upper left corner of the opening dialog Input options: Fixed (in pixels) As an IEC variable (integer data type) Placeholder: `ElementRectangle.ptTopLeft.iX` The placeholder is replaced by the position of the upper left corner of the element. Placeholder:`ElementRectangle.ptBottomRight.iX` The placeholder is replaced by the position of the lower right corner of the element.
Y	Vertical Y-position for the upper left corner of the opening dialog Input options: Fixed (in pixels) As an IEC variable (integer data type) Placeholder: `ElementRectangle.ptTopLeft.iY` At runtime, the dialog is displayed at the position of the upper left corner of the calling element Placeholder:`ElementRectangle.ptBottomRight.iY` The placeholder is replaced by the position of the lower right corner of the element.

Input Action: Change Language

Client-dependent language

The language can be switched individually for each client. The requirement is that the CODESYS Visualization add-on is installed in at least version 4.7.0.0 and the runtime system in version >= V3.5 SP20. When the visualization is started, it is displayed in the language set in the browser (for example, de or en). This language must be available in the project. If the language is not available, then the default texts are displayed.

In version 4.6.0.0 and lower, the language was switched for all clients simultaneously.

Language code

Use the ISO 639 code (for example, de, en, it, zh-CHS) to name a language which exists in the visualization.

Language

Language to which the current visualization client is switched

Example: en

: The Input Assistant offers all languages available in the project.

Input action: Change Shown Visualization

Table 110. Zoom to visualization

Visualization that is shown at the user input
Assign	Visualization that is selected from all available visualizations in the project or libraries. Example: `visMain`
Assign expression	Variable (`STRING`) that contains the name of the visualization Example: `PLC_PRG.strVisu` for the following application code: `strVisu: STRING := 'visMain';`
The order in which visualizations are displayed by user inputs is saved internally. The following options use this information.
Previous shown visualization	: Visualization that has already been shown before the current one Requirement: A visualization switch has already occurred.
Next shown visualization	: Visualization that is next in the call order after the current one Requirement: A visualization switch has already occurred which was called by Previous shown visualization.

Input action: Execute Command

Commands are listed here with transfer parameters that the visualization processes when an input event occurs.

Configure commands

Execute program on the plc
Execute program on client
Print
Navigate to URL (WebVisu)
Create Recipe
Read Recipe
Write Recipe
Write Recipe in File
Load Recipe from File
Delete Recipe

Click the symbol to add the selected command to the lower command list.

	The command in Configure commands is added to the list.
	The command is removed. Requirement: A command is selected.
The order in the list defines the order of execution.
	The selected command is moved down one position in the list.
	The selected command is moved up one position in the list.

Table 111. Command: Execute program on the plc

Command

1st parameter

2nd parameter

ExecutePlcProgram

'C:\programs\notepad.exe'

'Notes_A.txt'

EXE file that is executed on the controller

The program is executed on the PLC and therefore it must not be interactive or have any user interfaces.

It is possible, for example, for a program to copy a file.

Program name with directory as a string in single straight quotation marks

Arguments of the program as a string in single straight quotation marks

Example: Name of the file that the program opens

Table 112. Command: Execute program on client

Command

1. Parameters

2. Parameters

ExecuteClientProgram

'C:\programs\notepad.exe'

'Notes_A.txt'

EXE file that is executed on the display variant. Exception: WebVisu.

The program is executed within the context of the display variant. After this, the program may be interactive and have a user interface.

Program name with directory as STRING in single straight quotation marks

Arguments of the program as STRING in single straight quotation marks

Example: Name of the file that the program opens

Important

If the visualization is displayed as a CODESYS WebVisu, then no program (EXE file) can be started.

Table 113. Command: Navigate to URL (WebVisu)

Command

1. Parameters

2. Parameters

NavigateURL

'http://en.wikipedia.org'

PLC_PRG.stURL

'replace'

The visualization navigates to the web page of the URL.

Requirement: The visualization is executed as a CODESYS WebVisu.

. URL

As a literal in single straight quotation marks
As a variable (STRING)

If a parameter is not specified, then the web page is displayed in a new window or a new tab.

If 'replace' is specified, then the CODESYS WebVisu is replaced by the web page.

Table 114. Command: Read Recipe

Command	1st parameter	2nd parameter
`ReadRecipe`	`'RecipeDefinitionForModules'`	`'RecipeModuleA'`
	. Name of the recipe definition As a literal As a variable (`STRING`)	. Name of the recipe As a literal As a variable (`STRING`)
At visualization runtime, the controller reads the actual values from the variables of the recipe definition and writes them to the specified recipe. The values are saved implicitly (to a file on the controller) and shown in the recipe definition in the Recipe Manager of CODESYS. In other words, the recipe which is managed in CODESYS is updated with values from the controller.

Table 115. Command: Write Recipe

Command	1. Parameters	2. Parameters
`WriteRecipe`	`PLC_PRG.stRecipeDef`	`PLC_PRG.stRecipe`
	. Name of the affected recipe definition As a literal As a variable (`STRING`)	. Name of the recipe (from the recipe definition) As a literal As a variable (`STRING`)
At visualization runtime, the values of the recipe are written to the variables on the controller as they are in the Recipe Manager.

Table 116. Command: Save Recipe in File

Command	1. Parameters	2. Parameters
`SaveRecipeAs`	`PLC_PRG.stRecipeDef`	`PLC_PRG.stRecipe`
	. Name of the affected recipe definition As a literal As a variable (`STRING`)	. Name of the affected recipe that is updated and saved to a file As a literal As a variable (`STRING`) Optional parameter: If you do not specify a transfer parameter here, then the values from the recipe variables are saved only the file that is specified later. The implicit recipe files are not updated.
At visualization runtime, the Save Recipe as dialog opens and prompts the user for a file name and a storage location on the controller. The file name must not be `<recipe>.<recipe definition>`. The file extension is `.txtrecipe`. The user can then save the file that includes the actual values from the recipe variables. If a transfer parameter is not specified in the 2nd parameter, then the file is saved without changing an implicit recipe file. If a transfer parameter is given in the 2nd parameter, then the implicit recipe file is also updated. Note: If the Save recipe changes to recipe files automatically option is selected in the Recipe Manager – General tab, then the recipe definition in CODESYS and the implicit recipe files are kept the same automatically. Note: Implicit (automatically generated) recipe files exist on the controller with names in the following syntax: `<recipe>.<recipe definition>.txtrecipe`. These are typically used in the application as a buffer when reading and writing recipe variables.

Table 117. Command: Load Recipe from File

Command	1st parameter	2nd parameter
`LoadRecipeFrom`	`PLC_PRG.stReccipeDef`	`PLC_PRG.stReccipe`
	. Name of the affected recipe definition As a literal As a variable (`STRING`)	. Name of the affected recipe As a literal As a variable (`STRING`)
At visualization runtime, the Load Recipe dialog opens. It provides the visualization user with a file list that is located in the file system of the controller and filters by the extension `txtrecipe`. The selected file is downloaded. Then the recipes from the file are written to the implicit files and read to the given recipe in the recipe definition of the Recipe Manager. Requirement: The file was created with the `SaveRecipeAs` command.

Table 118. Command: Create Recipe

Command	1. Parameters	2. Parameters
`CreateRecipe`	`PLC_PRG.stRecipeDef`	`PLC_PRG.stRecipe_New`
	. Name of the affected recipe definition As a literal As a variable (STRING)	. Name of the new recipe As a literal As a variable (STRING)
At visualization runtime, a new recipe is created in the given recipe definition.

Table 119. Command: Delete Recipe

Command	1. Parameters	2. Parameters
`DeleteRecipe`	`PLC_PRG.stRecipeDef`	`PLC_PRG.stRecipe`
	. Name of the affected recipe definition As a literal As a variable (`STRING`)	. Name of the recipe As a literal As a variable (`STRING`)
At visualization runtime, the specified recipe is deleted from the recipe definition.

Table 120. Command: Print

Command	1. Parameters	2. Parameters
`Print`	Optional: File name for the visualization screen to be printed (example: "Start screen")	A second parameter cannot be specified for the `Print` command.
The default Printer dialog opens while the visualization is running. In the dialog, you select a printer and configure additional print settings. When you confirm the dialog, the currently displayed visualization screen is printed. Note The command can be executed in the TargetVisu only.

Input action: Switch Frame Visualization

When the input event occurs, the display switches to another visualization within one frame.

Frame selection type
Switch local visualization	The Frame Selection group is visible.
Switch to any visualization	The Frame and visualization selection group is visible.

Requirement: Switch local visualization is selected.
Frame selection	List of all frames that contain the active visualization. The referenced visualizations are listed below each frame, as determined in the References property of the respective frame. Example:
Assign selection	The selection in the Frame selection input field is accepted. Then it appears in the Selected frame and Selected visualization settings. Requirement: A visualization is selected in the Frame selection input field.
Selected Frame	Name of the frame to be switched to Example: `MainArea` Hint: Use the Assign selection command for changing the setting here.
Selected Visu	Name of the switched visualization Example: `visMainArea` Hint: Use the Assign selection command for changing the setting here.

Requirement: The Switch to any visualization option is selected.
Frame and visualization selection	Contains the frame to be switched to
Assign	Frame to be switched to (with complete path). The index determines the visualization. Example: `visMain.frameA.visB.frameB` The path is specified in the following syntax: `<visualization name>.<frame name> { <visualization name>.<frame name> }` Caution: Visualizations can be nested at any depth by means of frame elements. In order to use the Switch to any visualization frame selection type without any problems, a frame must not contain more than 21 referenced visualizations.
Assign expression	Variable (`STRING`) for the path of the frame to be switched to Example: `strFrane: STRING := 'visMain.frameA.visB.frameB';`
Index to select	. Index that determines which of the referenced visualizations is displayed As an integer As a variable (integer data type) Example :`PLC_PRG.iIndex` Note: The referenced visualizations of a frame are indexed automatically according to their order.

Requirement: The project contains visualizations that form a structure.

Input Action: Write Variable

The configuration of the input action defines how a visualization user specifies a value and to which variable the value is written.

Input type How the input is prompted
Default	Input field, or if necessary a virtual keyboard (if the display variant does not have a physical keyboard) Note: The default option for text input at runtime is set in the Visualization Manager: Dialog Settings tab, Settings for Default Text Input.
Text input	An input field is displayed. As the visualization user, you can use the keyboard to specify a number or a text. Requirement: The display variant has a keyboard as input device.
Text input with limits	An input field is displayed. You use the keyboard to specify a number or a text. The field also shows the value range for the input. When a limit is passed, the input value is displayed in red. Requirement: The display variant has a keyboard as input device.
VisuDialogs.Keypad	A virtual keyboard opens. You use it to specify a number or a text.
VisuDialogs.Numpad	A virtual keyboard opens. You use it to specify a number.
VisuDialogs.NumpadExtended	A virtual keyboard opens. You use it to specify a number. Hexadecimal and exponential notation are also permitted here.

Choose variable to edit
Use text output variable	: The input value is written to the text output variable of the element. This is the variable that is assigned in the Text variable → Text property.
Use another variable	: Variable where the input value is written. Example: `PLC_PRG.iVariable`
Initial display format	Placeholder with format definition. It defines the output format for the variable value and the input limits. Example: `%2.3f` for displaying the value as a decimal fraction.

Min	. Minimum value of the input limit. If a user specifies a lesser value, then it is not accepted. As a fixed value As a variable (data type corresponds to selected variable)
Max	. Maximum value of the input limit. If a user specifies a greater value, then it is not accepted. As a fixed value As a variable (data type corresponds to selected variable)
Dialog title	. Text displayed in the title bar of the dialog. Optional. As a fixed string Example: `Insert value` As a variable (`STRING`) Example: `PLC_PRG.stTitle : STRING := 'Insert value';`

Password field

standard icon : *** is displayed instead of the input text.

Position to Open Input Dialog	Initial position for the opening input dialog relative to the calling visualization
Use global setting (from the Visualization Manager)	Requirement: This option is available only when displaying on a TargetVisu or as a WebVisu. : The position which is set in the Visualization Manager on the Dialog settings tab is used.
Centered	: The dialog is displayed in the center.
Position	: The dialog is displayed at the position set below. Note: Use the corresponding input options for specifying the position in the X-direction and the Y-direction.
X	Horizontal X-position for the upper left corner of the opening dialog Input options: Fixed (in pixels) As an IEC variable (integer data type) Placeholder: `ElementRectangle.ptTopLeft.iX` The placeholder is replaced by the position of the upper left corner of the element. Placeholder:`ElementRectangle.ptBottomRight.iX` The placeholder is replaced by the position of the lower right corner of the element.
Y	Vertical Y-position for the upper left corner of the opening dialog Input options: Fixed (in pixels) As an IEC variable (integer data type) Placeholder: `ElementRectangle.ptTopLeft.iY` The placeholder is replaced by the position of the upper left corner of the element. Placeholder:`ElementRectangle.ptBottomRight.iY` The placeholder is replaced by the position of the lower right corner of the element.

Input action: Execute ST Code

Input field

Editor for code as structured text

Input action: Toggle Variable

Variable

Variable (BOOL) which is toggled when the input event occurs

Example: PLC_PRG.bSwitch

Input Action: File Transfer

With the File Transfer input action, a file can be transferred from an operating variant (target or web visualization) to the PLC as well as to and from the PLC. This works either by means of a file transfer (Type: File) or streaming (Type: Streaming).

The action has the effect that a file selection dialog is displayed in the visualization at runtime. There the visualization user can select a file which will be transferred either to or from the PLC: For a transfer from a PLC to the visualization, the Save File dialog opens. For the transfer from the visualization to the PLC, the Open File dialog opens.

Transfer
Direction	Direction of file transfer
From PLC to Visualization	The object specified in File name or Streaming instance name is transferred from the PLC to the visualization. The Save File file selection dialog is displayed in the visualization at runtime.
From Visualization to PLC	The file specified by the visualization user is transferred to the PLC and saved in the file path specified in File name or Streaming instance name. The Open File file selection dialog is displayed in the visualization at runtime.

Type	. Determines how the file is transferred Transfer type File: By file transfer Transfer type Streaming: By streaming

Type

File

The data transfer is done by file transfer.

File name

File path (type STRING) which describes the file in the file system

Variable
Example: strTransferFile: STRING;
Literal with relative path
Example: '/Recipes/Recipe_1.txt' saves the file in the directory Recipes.
Literal with placeholder $PLCLOGIC$
PlcLogic is the default resolution for the directory placeholder $PLCLOGIC$ .
Example: '$$PLCLOGIC$$/test.txt' saves the file in the directory PlcLogic.
Example: '$$PLCLOGIC$$/MyData/test.txt' saves the file in the directory PlcLogic/MyData.
Literal with placeholder $VISU$
visu is the default resolution for the placeholder $VISU$ .
Example: '$$VISU$$/test.txt' save the file in the subdirectory PlcLogic/visu. Alternatively, 'visu/test.txt' can also be specified.
Literal with absolute path
Example: 'E:\temp\test.txt'
Note: These kinds of file paths are not always supported.

Note

If a user specifies the file path in the visualization by means of a Text Field element, the masking character $ must not be included: $VISU$/dummy.txt

Note

In the case that the file path is specified by the user, it should be checked by the application in order to prevent files from being read or overwritten accidentally.

Type

Streaming

The data transfer is done by streaming.

Streaming instance name

Instance path (type IVisuStreamWriter or IVisuStreamReader) which describes the object in the file system of the controller

Type IVisuStreamReader for transfer direction From PLC to Visualization

Type IVisuStreamWriter for transfer direction From Visualization to PLC

Control flags

Note: The variable is evaluated only for transfer direction From Visualization to PLC.

Variable (type DWORD)

Determines how the object (file or instance object) is handled on the file system of the PLC. Two flags are provided for this with which the variable can be set.

Flag 1: VisuElems.VisuEnumFileTransferControlFlags.UseOriginalFileName
Flag 2: VisuElems.VisuEnumFileTransferControlFlags.ConfirmFileOverwriteInPlc

. Options

No flag set:
The user selects a file which is saved in the path specified in File name or Streaming instance name.
Flag 1 is set:
The path, which is specified by the user at visualization runtime, is applied and used as the path in the PLC file system.
Both flags are set:
The path is also checked. If an object already exists in the path specified on the client side, then a message prompt is displayed in the visualization. There the visualization user can confirm that the file will be overwritten.

Example: dwControlFlag

Example 49. Example

The transfer direction is From Visualization to PLC (write).

Example: A new recipe file Recipes/Recipe_2021.txt has been created in the visualization device. The visualization user selects this file and wants to save the file on the PLC under the same name. Because the control flags are set accordingly, a message window opens and the visualization user can confirm that the file will be overwritten.

PROGRAM PLC_PRG
VAR
    xVisuToggle : BOOL;
    dwControlFlag : DWORD := VisuElems.VisuEnumFileTransferControlFlags.UseOriginalFileName
                             + VisuElems.VisuEnumFileTransferControlFlags.ConfirmFileOverwriteInPlc;
    strFileName: STRING := '/Recipes/Recipe_new.txt';
END_VAR

Status Variables
Transfer active	Boolean variable (optional) `TRUE`: The transfer is in progress.
Transfer successful	Boolean variable (optional) `TRUE`: The transfer has completed successfully.
Error code	`0`: No errors `1`: Unspecified error `2`: Cancellation of file dialog `3`: Other file transfer in progress `4`: Error during file transfer `5`: Cancellation by timeout `6`: File read error – The file is not available or cannot be read. `7`: No device support for file transfer Possible causes: CODESYS WebVisu: File transfer is not possible by default. Communication with a controller of a version < 3.5.11: Functionality not implemented. Communication with a controller of a version >= 3.5.11: File transfer not activated (device description). Tip CODESYS manages this setting in the project settings.

Use local visualization files

Requirement: The option is available when Transfer visualization files to the PLC has been specified as the direction.

: The file selection dialog of the operating system is immediately displayed (default for a recently created input action).

: The file transfer dialog, which is available by default, opens and prompts you to select a file. You can adapt the dialog.
Hint: It is possible that the dialog is displayed in an inconvenient location and that the dialog layout does not correspond to that of the interface of the web visualization.

Dialog: Input Configuration

Are all element properties available?

Input action: User Management

Note

Input action: Close Dialog

Note

Note

Input Action: Open Dialog

Note

Note

Input Action: Change Language

Client-dependent language

Language code

Input action: Change Shown Visualization

Input action: Execute Command

Important

Note

Input action: Switch Frame Visualization

Input Action: Write Variable

Input action: Execute ST Code

Input action: Toggle Variable

Input Action: File Transfer

Note

Note

Tip